Workflow Schedule Template

The Workflow Schedule template demonstrates how BindAI represents and tracks workflows that are intended to execute at specific times or recurring intervals. A WorkflowSchedule stores the workflow identifier, the next scheduled execution time, an optional recurring interval, and whether the schedule is enabled. The WorkflowScheduler maintains registered schedules and identifies which schedules are currently due.

Purpose

This template demonstrates how to:

create a workflow schedule
register schedules with a scheduler
determine which schedules are due
configure recurring execution intervals
enable or disable schedules
advance recurring schedules after execution

Scheduling is kept separate from workflow execution itself.

Scheduling Architecture

The scheduling components are responsible for determining when a workflow should run.

WorkflowSchedule

      ↓

WorkflowScheduler

      ↓

Check Due Schedules

      ↓

Workflow Execution

The scheduler does not execute the workflow itself. It identifies schedules that are ready for execution so that application code can start the corresponding workflow.

Workflow Schedule

A WorkflowSchedule describes one scheduled workflow. The current implementation contains four fields:

WorkflowSchedule(
    workflow_id="daily-report",
    next_run=...,
    interval_seconds=3600,
    enabled=True,
)

The fields are:

Field	Description
`workflow_id`	Identifier of the workflow to execute
`next_run`	The next scheduled execution time
`interval_seconds`	Optional interval for recurring execution
`enabled`	Whether the schedule is active

Registering a Schedule

Schedules are registered with WorkflowScheduler.

scheduler = WorkflowScheduler()

scheduler.add(
    WorkflowSchedule(
        workflow_id="daily-report",
        next_run=scheduled_time,
        interval_seconds=3600,
    )
)

The scheduler stores the schedule in its internal schedule collection. Multiple schedules can be registered with the same scheduler.

Checking Due Schedules

The scheduler provides the due() method to identify schedules whose execution time has arrived. Conceptually:

Current Time

↓
Compare with next_run

↓
next_run <= current time?

      ↙          ↘

    Yes           No

     ↓             ↓

   Due          Not Due

Only schedules that are:

enabled, and
whose next_run is at or before the current time

are returned.

Due Schedule Example

Suppose the scheduler contains three schedules:

Report       09:00
Backup       10:00
Sync         11:00

If the current time is 10:30:

Report  ✓ Due

Backup  ✓ Due

Sync    ✗ Not Due

Calling:

due_schedules = scheduler.due()

returns the schedules that are currently due.

Enabled Schedules

Only enabled schedules are considered by due().

WorkflowSchedule(
    workflow_id="report",
    next_run=scheduled_time,
    enabled=True,
)

An enabled schedule can be returned when its next_run has arrived.

Disabled Schedules

A disabled schedule remains registered but is ignored when checking for due schedules.

WorkflowSchedule(
    workflow_id="report",
    next_run=scheduled_time,
    enabled=False,
)

Even if its next_run is in the past, due() does not return it. This allows applications to temporarily disable scheduled workflows without removing their schedule.

One-Time Schedule

A schedule without an interval can represent a one-time execution.

WorkflowSchedule(
    workflow_id="monthly-report",
    next_run=scheduled_time,
    interval_seconds=None,
)

After the schedule becomes due, calling reschedule() does not move its next_run because no recurring interval is configured. The application can therefore treat the schedule as a one-time schedule.

Recurring Schedule

A recurring schedule specifies interval_seconds.

WorkflowSchedule(
    workflow_id="hourly-sync",
    next_run=scheduled_time,
    interval_seconds=3600,
)

After the schedule has been processed, the scheduler can advance it:

scheduler.reschedule(schedule)

The next execution time is calculated by adding the configured interval.

09:00

↓ + 1 hour

10:00

↓ + 1 hour

11:00

↓ + 1 hour

12:00

Rescheduling

The reschedule() method updates recurring schedules. Conceptually:

Current next_run

        +

interval_seconds

        ↓

New next_run

For example:

next_run = 09:00
interval_seconds = 3600

After rescheduling:

next_run = 10:00

If interval_seconds is not configured, the schedule is not advanced.

Scheduler Lifecycle

A typical application-level scheduling cycle looks like this:

Register Schedules

       ↓

Check Due Schedules

       ↓

Start Due Workflows

       ↓

Reschedule Recurring Schedules

       ↓

Check Again

The current WorkflowScheduler provides the registration, due-checking, and rescheduling portions of this lifecycle. The surrounding application is responsible for deciding how and when to call these methods and how to execute the returned workflows.

Scheduler Does Not Execute Workflows

The scheduler itself does not invoke a workflow executor. Its responsibility is to identify schedules that are ready.

WorkflowScheduler

       ↓

due()

       ↓

Due Schedule

       ↓

Application

       ↓

Workflow Execution

This separation keeps scheduling logic independent from workflow execution.

Scheduler vs Workflow Executor

The scheduler and executor have different responsibilities.

Scheduler	Executor
Tracks schedules	Executes workflows
Determines what is due	Runs workflow nodes
Manages `next_run`	Manages execution state
Handles recurring intervals	Handles workflow completion/failure
Does not execute nodes	Executes nodes

The scheduler answers when should this workflow run? The executor answers how should this workflow execute?

Scheduler vs Loop

Scheduling and loops both support repeated behavior, but at different levels.

Scheduler	Loop
Repeats over time	Repeats during workflow execution
Uses timestamps	Uses a predicate
Creates opportunities for new executions	Continues the current workflow
Background/application-level mechanism	Workflow-level control flow

A scheduler controls when a workflow starts. A loop controls how a running workflow repeats.

Example: Hourly Workflow

An application may register an hourly workflow:

schedule = WorkflowSchedule(
    workflow_id="hourly-report",
    next_run=scheduled_time,
    interval_seconds=3600,
)

The application periodically checks:

for schedule in scheduler.due():
    # Start the corresponding workflow
    # Then advance recurring schedules
    scheduler.reschedule(schedule)

The scheduler therefore maintains the timing state while workflow execution remains separate.

Multiple Schedules

A single scheduler can contain multiple workflows.

Workflow Scheduler

├── Daily Report
├── Hourly Sync
├── Data Backup
└── Knowledge Refresh

Calling due() evaluates all registered schedules and returns the enabled schedules whose next_run has arrived.

Current Time Handling

The current implementation determines due schedules using:

datetime.utcnow()

Therefore, the scheduler currently compares next_run against the UTC-based current time returned by datetime.utcnow(). Applications should ensure that the timestamps supplied to WorkflowSchedule are consistent with the time basis expected by the scheduler. Timezone conversion and user-facing local scheduling are application-level concerns and are not currently implemented by WorkflowScheduler.

Recurring Execution

Recurring schedules are represented using an interval rather than a separate recurrence rule. For example:

interval_seconds=86400

represents a 24-hour interval. Common examples include:

     → 1 minute
   → 1 hour
  → 1 day
604800   → 1 week

The scheduler simply adds the configured number of seconds to next_run.

Typical Use Cases

The scheduling mechanism can support workflows such as:

periodic reports
recurring data synchronization
scheduled document processing
periodic knowledge refreshes
recurring maintenance
automated backups
monitoring workflows
periodic AI processing

The actual workflow execution remains handled by the workflow system outside the scheduler.

Schedule State

A schedule has a small and explicit state model:

workflow_id
     +
next_run
     +
interval_seconds
     +
enabled

This makes schedules simple to persist, inspect, and manage.

Best Practices

Use a consistent time basis for next_run.
Keep recurring intervals explicit.
Disable schedules that should temporarily stop running.
Reschedule recurring schedules after processing them.
Keep scheduling separate from workflow execution.
Avoid registering duplicate schedules unintentionally.
Monitor overdue schedules in the surrounding application.
Ensure scheduled workflows can safely execute more than once when using recurring schedules.

The Schedule template works well alongside:

Workflow Retry
Workflow Timeout
Workflow Parallel
Workflow Human

Scheduling determines when execution should occur, while these other workflow features determine how execution behaves.

Summary

The Workflow Schedule template demonstrates how BindAI represents and manages time-based workflow execution. WorkflowSchedule stores the workflow identifier, next execution time, optional recurrence interval, and enabled state. WorkflowScheduler provides three core operations:

add()

↓

due()

↓

reschedule()

Together, these components allow applications to register scheduled workflows, identify which schedules are due, and advance recurring schedules while keeping scheduling separate from actual workflow execution.

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

08.8 workflow schedule

Workflow Schedule Template

Purpose

Scheduling Architecture

Workflow Schedule

Registering a Schedule

Checking Due Schedules

Due Schedule Example

Enabled Schedules

Disabled Schedules

One-Time Schedule

Recurring Schedule

Rescheduling

Scheduler Lifecycle

Scheduler Does Not Execute Workflows

Scheduler vs Workflow Executor

Scheduler vs Loop

Example: Hourly Workflow

Multiple Schedules

Current Time Handling

Recurring Execution

Typical Use Cases

Schedule State

Best Practices

Summary

​Workflow Schedule Template

​Purpose

​Scheduling Architecture

​Workflow Schedule

​Registering a Schedule

​Checking Due Schedules

​Due Schedule Example

​Enabled Schedules

​Disabled Schedules

​One-Time Schedule

​Recurring Schedule

​Rescheduling

​Scheduler Lifecycle

​Scheduler Does Not Execute Workflows

​Scheduler vs Workflow Executor

​Scheduler vs Loop

​Example: Hourly Workflow

​Multiple Schedules

​Current Time Handling

​Recurring Execution

​Typical Use Cases

​Schedule State

​Best Practices

​Related Templates

​Summary

Workflow Schedule Template

Purpose

Scheduling Architecture

Workflow Schedule

Registering a Schedule

Checking Due Schedules

Due Schedule Example

Enabled Schedules

Disabled Schedules

One-Time Schedule

Recurring Schedule

Rescheduling

Scheduler Lifecycle

Scheduler Does Not Execute Workflows

Scheduler vs Workflow Executor

Scheduler vs Loop

Example: Hourly Workflow

Multiple Schedules

Current Time Handling

Recurring Execution

Typical Use Cases

Schedule State

Best Practices

Related Templates

Summary